From 26a5391caa4add24b774115e46ad2f2836fb8b05 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Fri, 18 Jan 2013 19:28:58 -0600 Subject: [PATCH] Add some missing docs for GtkPlacesSidebar Signed-off-by: Federico Mena Quintero --- gtk/gtkplacessidebar.c | 9 ++++++++- gtk/gtkplacessidebar.h | 27 +++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/gtk/gtkplacessidebar.c b/gtk/gtkplacessidebar.c index 4b9e814c75..f944fb7e16 100644 --- a/gtk/gtkplacessidebar.c +++ b/gtk/gtkplacessidebar.c @@ -108,7 +108,7 @@ * While bookmarks are completely in control of the user, the places sidebar also * allows individual applications to provide extra shortcut folders that are unique * to each application. For example, a Paint program may want to add a shortcut - * for a Clipart folder. + * for a Clipart folder. You can do this with gtk_places_sidebar_add_shortcut(). * * To make use of the places sidebar, an application at least needs to connect * to the #GtkPlacesSidebar::open-location signal. This is emitted when the @@ -3768,6 +3768,13 @@ gtk_places_sidebar_style_set (GtkWidget *widget, update_places (sidebar); } +/** + * gtk_places_sidebar_new: + * + * Creates a new #GtkPlacesSidebar widget. The application should connect + * to at least the #GtkPlacesSidebar::open-location signal to be notified + * when the user makes a selection in the sidebar. + */ GtkWidget * gtk_places_sidebar_new (void) { diff --git a/gtk/gtkplacessidebar.h b/gtk/gtkplacessidebar.h index 27f626e7c4..15acca925e 100644 --- a/gtk/gtkplacessidebar.h +++ b/gtk/gtkplacessidebar.h @@ -44,6 +44,33 @@ G_BEGIN_DECLS typedef struct _GtkPlacesSidebar GtkPlacesSidebar; typedef struct _GtkPlacesSidebarClass GtkPlacesSidebarClass; +/** + * GtkPlacesOpenFlags: + * @GTK_PLACES_OPEN_NORMAL: This is the default mode that #GtkPlacesSidebar uses if no other flags + * are specified. It indicates that the calling application should open the selected location + * in the normal way, for example, in the folder view beside the sidebar. + * @GTK_PLACES_OPEN_NEW_TAB: When passed to gtk_places_sidebar_set_open_flags(), this indicates + * that the application can open folders selected from the sidebar in new tabs. This value + * will be passed to the #GtkPlacesSidebar::open-location signal when the user selects + * that a location be opened in a new tab instead of in the standard fashion. + * @GTK_PLACES_OPEN_NEW_WINDOW: Similar to @GTK_PLACES_OPEN_NEW_TAB, but indicates that the application + * can open folders in new windows. + * + * These flags serve two purposes. First, the application can call gtk_places_sidebar_set_open_flags() + * using these flags as a bitmask. This tells the sidebar that the application is able to open + * folders selected from the sidebar in various ways, for example, in new tabs or in new windows in + * addition to the normal mode. + * + * Second, when one of these values gets passed back to the application in the + * #GtkPlacesSidebar::open-location signal, it means that the application should + * open the selected location in the normal way, in a new tab, or in a new + * window. The sidebar takes care of determining the desired way to open the location, + * based on the modifier keys that the user is pressing at the time the selection is made. + * + * If the application never calls gtk_places_sidebar_set_open_flags(), then the sidebar will only + * use #GTK_PLACES_OPEN_NORMAL in the #GtkPlacesSidebar::open-location signal. This is the + * default mode of operation. + */ typedef enum { GTK_PLACES_OPEN_NORMAL = 1 << 0, GTK_PLACES_OPEN_NEW_TAB = 1 << 1, -- 2.30.2